---
title: Graphics
slug: /graphics
section: Graphics
---

Graphics are special object that abstract something that can be drawn to the screen. Examples include [circles](#circle), [polygons](#polygon), and [sprites](/docs/sprites).

:::warning

The [[GraphicsComponent]] centers graphics by default, set the actor.graphics.anchor to change this behavior.

:::

## Graphics

Excalibur `ex.Graphic`s break into 2 main categories, [[Sprite]] based and [[Raster]] based. That is to say Raster and non-Raster graphics.

All [[Graphic|Graphics]] have a bunch of useful feature that work for ALL types of graphics

- `clone(): Graphic`

  - Returns a new deep copy of this graphic

- `width: number`

  - Gets or sets the width of the graphic

- `height: number`

  - Gets or sets the height of the graphic

- `flipHorizontal: boolean`

  - Gets or sets the flipHorizontal, which will flip the graphic horizontally (across the y axis)

- `flipVertical: boolean`

  - Gets or sets the flipVertical, which will flip the graphic vertically (across the x axis)

- `rotation: number`

  - Gets or sets the rotation of the graphic (in radians)

- `opacity: number`

  - Gets or sets the opacity of the graphic, 0 is transparent, 1 is solid (opaque).

- `scale: Vector`

  - Gets or sets the scale of the graphic, this effects the width and height of the graphics

- `origin: Vector`

  - Gets or sets the origin of the graphic, if not set the center of the graphic is the origin


- `tint: Color`

  - Applies a multiplicative tint to the pixels in the graphic. This is useful if you want to quickly tweak the color or a graphic without making new assets.

:::note

Multiplicative tint this means you cannot apply a `Color.White` tint to a graphic that will have an effect, under the hood the white color is represented as `(1, 1, 1)` and 1 multiplied against anything is itself.

:::

### Raster Graphics

Rasters are a type of `ex.Graphic` built by constructing a bitmap (using CanvasRenderingContext2D) in memory which is then sent to the drawing context. This allows the use of features available to developers in the 2D canvas to produce Graphics for Excalibur. It's important to share or limit the number of Raster graphics due to their memory footprint in the browser.

Rasters are only rendered when they need to be, if no properties change on them, they are not recalculated. Rasters can be forced to be re-draw by calling `.flagDirty()`.

See these useful raster implemenations

- [Text](#Text)
- [Polygon](#Polygon)
- [Rectangle](#Rectangle)
- [Circle](#Circle)
- [Canvas](#Canvas)

A custom raster can be built implementing the `execute` function, this is in fact how the [[Canvas]] is implemented.

```typescript
export class MyRaster extends ex.Raster {
  constructor() {
    super();
  }

  execute(ctx: CanvasRenderingContext2D): void {
    // my custom raster
    ctx.fillStyle = 'blue';
    ctx.fillRect(0, 0, 20, 20);
  }
}
```

`ex.Raster` properties and methods

- `abstract execute(ctx: CanvasRenderingContext2D): void`

  - This is the bitmap generation implementation, this will construct the desired bitmap on the CanvasRenderingContext2D.

- `rasterize(): void`

  - This causes the underlying bitmap to be generated calling the `execute()` implementation in the process

### Polygon

Polygon creates a rastered polygon graphic given a set of points

```typescript
const triangle = new ex.Polygon({
  points: [ex.vec(10 * 5, 0), ex.vec(0, 20 * 5), ex.vec(20 * 5, 20 * 5)],
  color: ex.Color.Yellow
});
```

### Circle

Circle creates a rastered circle graphic given a raidus

```typescript
const circle = new ex.Circle({
  radius: 10,
  color: ex.Color.Red
});
```

### Rectangle

Rectangle creates a rastered rectange graphic given a width and height

```typescript
const rect = new ex.Rectangle({
  width: 100,
  height: 100,
  color: ex.Color.Green
});
```

### Canvas

The canvas is a special type of raster graphic that acts like a shim between direct CanvasRenderingContext2D drawing and the [ExcaliburGraphicsContext](#ExcaliburGraphicsContext)

This type of raster is re-rendered every time the graphic is drawn, thus it should be used sparingly due to this inefficiency.

```typescript
const canvas = new Canvas({
  draw: (ctx: CanvasRenderingContext2D) => {
    ...
  }
});
```
